//+------------------------------------------------------------------+
//|                                                ArrayFunction.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include "CompareFunction.h"                     // 基础比较工具函数（支撑元素相等性判断）
#include <Generic/Interfaces/IComparer.h>        // 比较器接口（支撑自定义排序规则的二分查找）

//+------------------------------------------------------------------+
//| 数组二分查找函数：在**已排序**的一维数组指定范围内查找目标元素      |
//| 核心特性：                                                      |
//|  1. 依赖排序：仅支持**已按比较器规则排序**的数组（升序/降序由比较器定义）； |
//|  2. 高效查找：时间复杂度 O(log n)，远快于线性查找（O(n)）；          |
//|  3. 精确匹配：找到时返回元素索引；未找到时返回“最接近目标值的前一个元素索引”； |
//| 适用场景：所有基于**已排序数组**的高效查找场景，如：               |
//|  - 有序配置表查询（如按ID排序的用户配置数组，快速查找指定用户）；     |
//|  - 数值范围定位（如按价格排序的订单数组，快速定位目标价格附近的订单）； |
//|  - 字典/索引表查询（如按关键词排序的词典数组，快速查找目标词汇）；     |
//+------------------------------------------------------------------+
template<typename T>
int ArrayBinarySearch(
    T &array[],                // [in] 目标数组（**必须已按比较器规则排序**，否则结果不可靠）
    const int start_index,     // [in] 查找起始索引（≥0，且 < ArraySize(array)）
    const int count,           // [in] 查找元素数量（≥0，且 start_index + count ≤ ArraySize(array)）
    T value,                   // [in] 待查找的目标元素（类型与数组元素一致）
    IComparer<T>* comparer     // [in] 元素比较器（实现 IComparer<T> 接口，定义数组排序规则；NULL 会导致查找失败）
);

//+------------------------------------------------------------------+
//| 数组首次索引查找函数：在一维数组指定范围内**从左到右**查找目标元素的首次出现位置 |
//| 核心特性：                                                      |
//|  1. 无序兼容：支持**未排序**数组（无排序依赖）；                    |
//|  2. 线性遍历：时间复杂度 O(n)，适用于小规模数组或非频繁查找场景；     |
//|  3. 首次匹配：找到时返回**第一个**匹配元素的索引；未找到时返回 -1；     |
//| 适用场景：所有需要**查找元素首次出现位置**的场景（无论数组是否排序），如： |
//|  - 日志数组分析（查找某类日志首次出现的位置，定位问题起始点）；       |
//|  - 重复元素去重（找到首个重复元素索引，进行删除操作）；             |
//|  - 无序数据定位（如随机存储的订单数组，查找首个满足条件的订单）；     |
//+------------------------------------------------------------------+
template<typename T>
int ArrayIndexOf(
    T &array[],                // [in] 目标数组（支持有序/无序，无排序依赖）
    T value,                   // [in] 待查找的目标元素（类型与数组元素一致，通过 ::Equals 函数判断相等性）
    const int start_index,     // [in] 查找起始索引（≥0，且 < ArraySize(array)；超出范围时返回 -1）
    const int count            // [in] 查找元素数量（≥0，且 start_index + count ≤ ArraySize(array)；超出范围时返回 -1）
);

//+------------------------------------------------------------------+
//| 数组末次索引查找函数：在一维数组指定范围内**从右到左**查找目标元素的末次出现位置 |
//| 核心特性：                                                      |
//|  1. 无序兼容：支持**未排序**数组（无排序依赖）；                    |
//|  2. 线性遍历：时间复杂度 O(n)，适用于小规模数组或非频繁查找场景；     |
//|  3. 末次匹配：找到时返回**最后一个**匹配元素的索引；未找到时返回 -1；   |
//| 适用场景：所有需要**查找元素末次出现位置**的场景（无论数组是否排序），如： |
//|  - 历史记录分析（查找某操作最后一次执行的日志位置，定位最新状态）；     |
//|  - 缓存数据清理（查找某key最后一次出现的缓存位置，优先保留最新数据）；  |
//|  - 重复元素处理（找到最后一个重复元素索引，进行合并/删除操作）；       |
//+------------------------------------------------------------------+
template<typename T>
int ArrayLastIndexOf(
    T &array[],                // [in] 目标数组（支持有序/无序，无排序依赖）
    T value,                   // [in] 待查找的目标元素（类型与数组元素一致，通过 ::Equals 函数判断相等性）
    const int start_index,     // [in] 查找起始索引（≥0，且 < ArraySize(array)；超出范围时返回 -1）
    const int count            // [in] 查找元素数量（≥0，且 start_index - count + 1 ≥ 0；超出范围时返回 -1）
);

//+------------------------------------------------------------------+
//| 数组元素反转函数：将一维数组指定范围内的元素**首尾颠倒**（逆序排列）   |
//| 核心特性：                                                      |
//|  1. 原地操作：直接修改原数组，无需额外分配内存（空间复杂度 O(1)）；    |
//|  2. 高效逆序：时间复杂度 O(n)（n 为 count，仅需遍历一半元素进行交换）； |
//|  3. 范围灵活：支持对数组任意连续子区间进行反转（全数组反转可设置 start_index=0，count=ArraySize(array)）； |
//| 适用场景：所有需要**逆序数组元素**的场景，如：                     |
//|  - 数据展示调整（如按时间升序的日志数组，反转后按时间降序展示）；     |
//|  - 算法辅助操作（如栈/队列的顺序转换，反转数组实现队列到栈的逻辑）；   |
//|  - 字符串处理（如字符数组反转，实现字符串倒序功能）；               |
//|  - 排序结果调整（如升序数组反转后变为降序，避免重新排序）；           |
//+------------------------------------------------------------------+
template<typename T>
bool ArrayReverse(
    T &array[],                // [in/out] 目标数组（直接修改原数组元素顺序，无需返回新数组）
    const int start_index,     // [in] 反转起始索引（≥0，且 < ArraySize(array)；无效时返回 false）
    const int count            // [in] 反转元素数量（≥0，且 start_index + count ≤ ArraySize(array)；无效时返回 false）
);
//+------------------------------------------------------------------+